spr_fsi
=======

Version 1.41 (13-Jul-2002)
SPRtools block 1h release.
(C) 1993-9 DEEJ Technology PLC

Features
--------
Sprite processing tools, features provided;

        Increase / Decrease bits per pixel (number of colours),
        Floyd Steinburg Integer dithering,
        Image scaling with true sub-sampling (anti-aliasing) and interpolation,
        Image cropping
        Dynamic intensity range expansion,
        Gamma correction,
        Image inversion,
        Filters including smoothing, sharpening, noise removal & user defined
        Support for common fixed palettes,
        Palette optimisation,

Restrictions
------------
Enough memory must be available to hold the source image and two lines of
the destination image. Further memory is required by certain operations
such as filtering. Palette optimisation can require a large amount of memory
for images with thousands of colours.

Only the first sprite in the file is recognised.

Syntax
------
spr_fsi [-bpp <bpp>]
	[-scale <scale>]
	[-crop <crop>]
	[-palette <palette>]
	[-invert]	
	[-expand]
	[-gamma <gamma>]
	[-filter <filter>]
	[-aspect]
	[-nodither]
	[-nointerp]
	[-quiet]
	[-help]
	[-in <input sprite file>]
	[-out <output sprite file>]
	[-err <progress/error file>]

Options may be abrieviated to the minimum unique form.
All options and parameters are case specific.

Files default to stdin and stdout with progress or errors to stderr.

-bpp <bpp>
<bpp>	= {1 | 2 | 4 | 8 | 15 | 24 }

		Bits per pixels in the output image. The default is 24.
		The 24 bpp option produces the standard 24/32 bit deep sprite
		format, a (non-standard) true 24 format is also available,
		which is described later.

-scale <scale>
<scale> = {<xsize> ,<Ysize> |
	   <XYmul>:<XYdiv>  | 
	   <Xmul>:<Xdiv>,<Ymul>:<Ydiv> }

		The amount the scale the output image can be specified in
		three ways.

		<Xsize>,<Ysize> scales to an absolute size
		e.g. -scale 1280,1024 for a sprite 1280x1024 pixels

		<XYmul>:<XYdiv> scales both axis by the same ratio
		e.g. -scale 3:2 to expand by 3/2 (1.5)

		<Xmul>:<Xdiv>,<Ymul>:<Ydiv> scales each axis separately
		e.g. -scale 3:2,1:2 to expand horizontally by 3/2
                                and reduce vertically by 1/2

		Scales which would produce a very small output sprite, or
		equate to an expansion of more than 128x in any direction are 
		prevented. The scale defaults to 1:1 in each direction, unless
		the input image has rectangular pixels and the -aspect flag is
		not set, in this case a scale of 1:1,2:1 is used to covert the
		sprite to use square pixels.
	
-crop <crop>
<Crop> = <left>,<top>,{<right>  | <+Xsize> | <-right>},
                      {<bottom> | <+Ysize> | <-bottom>}
                      
                 Crops the source image to the desired size.

                 For a source image of 160x128, to crop 5 pixels from
                 each edge the following could be used.
                                  
                 e.g. -crop 5,5,-5,-5
                 or   -crop 5,5,145,123
                 or   -crop 5,5,+150,+118

-palette <palette>
<palette> = {rgb | grey | desktop | win3 | fix | opt }

		Selects the palette type for output sprites with 1-8 bpp.
		The palette defaults to the same as the input sprite.
		If the input sprite does not have a palette, the default for
		a RISC OS mode with the same bpp is used. Certain palette
		types may only be used for some numbers of bits per pixel in
		the output sprite.

		The rgb palette can be used with bpp 4 and 8. In 4 bpp the
		palette gives 9 grey levels, 6 fully saturated colours and
		orange, in a layout designed to be desktop friendly. In 8 bpp
		the palette gives 46 grey levels plus a 6x6x6 level RGB colour
		cube (combinations of 6 levels for each component).

		The grey palette gives linear grey scales for bpp 1-8,
		giving 2 to 256 grey levels.
		
		The desktop palette gives the standard 16 colour RISC OS
		desktop palette in 4 bpp, and the standard VIDC1 256 colour
		mode palette in 8 bpp. 

		The win3 palette gives a Windows 3 palette in 4 bpp,
		consisting of 4 grey levels, 6 fully saturated colours and 
		6 half brightness colours. In 8 bpp a custom (non-Windows) 
		palette with 176 grey levels, a 4x4x4 level colour cube plus 
		18 RGYBMC shades is used.

		The fix palette will use the input sprites palette (or the
		default) but will convert old type 12 bit palettes stored in
		the sprite to full 24 bit. e.g. &B0G0R0xx to &BBGGRRxx

		The opt palette will examine the input sprite after all
		pre-processing operations have been performed, and will choose
		the best combination of colours to use in the output image.
		More details on this process are given below. This option
		can only be used for output sprites of 4 or 8 bpp.

-invert		Invert the source image before processing.

-expand		Expand the dynamic range the source image before processing.
		Expand works by finding the lowest and highest intensity pixels
		in the image, the colours of all pixels in the image are then
		adjusted so that the intensities range from zero to maximum.

-gamma <gamma>
<gamma>	= positive floating point number

		Gamma correction can be performed on the source image before
		processing. The default value is 1.0 which has no effect.
		Values >1.0 (2.2 is the recognised standard) are used to move
		the contrast detail in the image to the brighter part of the
		intensity range. This use useful for correcting scanned images
		and for preparing sprites for printing. Values less than 1.0
		can be used to move detail to darker intensities.

-filter <filter>
<filter> = {filter> | <user filter> }

		Filters can be used to perform a variety of image processing
		on the image before further processing. See later for a
		description of how filtering works.

<standard filter> = filter name:-
		sharpen1 - Sharpen week
		sharpen2 - Sharpen medium
		sharpen3 - Sharpen strong
		smooth1  - Smooth week
		smooth2  - Smooth medium
		smooth3  - Smooth strong
		average  - Averages with surrounding pixels
		noise1   - Noise removal week
		noise2   - Noise removal medium
		noise3   - Noise removal strong
		edge     - Horizontal and vertical edge extraction
		edgeV    - Vertical edge extraction
		edgeH    - Horizontal edge extraction
		edgeNW   - Edge extraction along a 45 degree angle
		edgeNE   - Edge extraction along a 45 degree angle
		edgeSW   - Edge extraction along a 45 degree angle
		edgeSE   - Edge extraction along a 45 degree angle
		emboss1  - 3D embossing effect
		emboss2  - 3D embossing effect, inverted

<user filter> = <a>,<b>,<c>,<d>,<e>,<f>,<g>,<h>,[<mul>,[<div>,[<add>,[<diff>]]]]
		Where <a> to <h> are the rows and columns of the 3x3 filter
		matrix. <mul> and <div> are the summation scaling factors which
		default to 1. <add> is an optional component to be added after
		scaling. <diff> is the optional noise filtering level.
		All numbers are positive or negative integers except <div> and
		<diff> which must be positive.
		
-aspect		Normally all sprites containing rectangular pixels are 
converted
		to square pixels during processing (doubling the Y resolution),
		if the -aspect flag is given a rectangular pixel input sprite
		will give a rectangular pixel output sprite.

-nodither	This option can be used to prevent Floyd Steinburg Integer
		dithering from being used during processing. This will speed
		up processing but will result in a poor quality output. It
		has no effect when the output sprite is 24 bpp.

-nointerp	This option prevents pixel area summing or interpolation being
		used when scaling the image (see the section below on scaling).
		This will speed up the scaling of images, but with a reduction
		in quality. It can be used when scaling up an image to prevent
		the loss of sharpness caused by interpolation.

-quiet		Prevents the printing of the state of options on stderr during
		processing.  Progress and errors are still output.

-help		Prints a syntax summary.


Info
----
True 24 bit sprite format:
		spr_fsi normally produces standard RISC OS deep sprite 24/32
		bpp format when using -bpp 24, this format is 25% larger than
		other 24 bit formats and does not compress as well.

		By using -bpp 8 -palette rgb a non standard true 24 bit deep
		sprite can be produced. It will not be understood by RISC OS
		applications, but can be used as a storage format for sprites
		to be used again with spr_fsi.

		The format has a sprite mode specifier of type 8 (currently
		unassigned in RISC OS 3.5) and stores pixels as consecutive
		three byte quantities (blue, green and red bytes) padded to
		the next word boundary at the end of each line.

Scaling		spr_fsi uses two techniques to improve the scaling of images.
		The first is used when scaling down an image, where each output
		pixel will depend on many pixels in the input. An area of the
		source image corresponding to a pixel in the destination image
		is summed to give an average colour. This achieves the effect
		of anti-aliasing which reduces loss of detail due to scaling
		down.

		When scaling up a pixel in the input is converted to many 
		pixels in the output. To prevent a blocky image pixels are 
		interpolated to achieve a smooth graduation between them,
		rather than sharp boundary. This produces a much smoother
		image at the expense of some sharpness (the image can be
		pre-sharpend first using a filter).

		If the image is being scaled up in one direction and reduced
		in another the two techniques are used together. Anti-aliasing
		and interpolation may be turned off using -nointerp.

Optimised palette
		When reducing the number of bits per pixel of an image the
		various fixed palette types can be chosen to represent colours
		which will be close to the original. Most fixed palettes aim
		to cover the colour cube by providing shades which have
		combinations red, green and blue ranging from zero to maximum.

		These fixed palettes work well for images which have a large
		range of colours spanning the colour cube, but where an image
		has for example, a large number of green shades, a few reds
		and no blues, many colours in the fixed palette will not be
		used, and the green shades will be reduced to a far few
		number in the output. In this case a palette with more green
		shades and no blue would be more appropriate.

		When reducing images down to 8 (or 4) bpp the -palette opt
		option will cause the input sprite to be analysed and the
		256 (or 16) colours which will give the best possible match
		to the original image chosen, and used in the output images
		palette.

		After any pre-processing operations have been performed, a
		histogram of all the colours used in the input image is
		built. The histogram is then filtered to remove colours which
		are only used a few times to reduce the amount of calculation.
		The remaining colours are picked out so as to reduce the
		difference between the source and destination images as much
		as possible. This is calculated by the amount of use of the
		colour and how close similar colours are to it.

		Usually the optimised palette will generate an image which
		is much closer to the original, with dithering greatly reduced.
		For some images however, the results may not be as pleasing
		as one of the fixed palettes. Experimentation may be necessary.

Filters		Filters work by taking a pixel and modifying its value
		depending on the 8 surrounding pixels. The filter consists of
		a 3 by 3 matrix, the center corresponding to the current pixel.
		The values in the matrix are used to multiply the value of the
		pixel under it, values may be positive or negative

		e.g. 1 2 1    The center pixel is multiplied by 4, its 
		     2 4 2    neighbours horizontally an vertically are
		     1 2 1    multiplied by 2, and its diagonals by 1.

		The sum of the nine pixels multiplied by the matrix elements
		is multiplied and divided by scaling factors to reduce its
		range back to the valid values for a pixel. In the above
		example the sum comes to 16x, so it must be divided by 16.

		Another value may be added to the sum to brighten the pixel
		(+ve) or darken it (-ve).

		Finally a differencing filter value can be given. If the
		difference between the original pixel and the result of the
		above process is greater than the difference value the pixel
		is unchanged, other wise it is replaced with the filtered
		value. If no difference is given the pixel is always replaced.

		Filters work on each colour component separately and can
		produce colour changes, e.g. the edge extracting filter.
		Filters work on the input image and can only use the closest
		colours in the input image to represent the desired filter
		values. It is recommended that filter is done with as many
		bits per pixel as possible. e.g. if an 8 bpp image is going
		to be filtered to and increased to 24bpp, the increase depth
		is done first, followed by another run to do the filtering.

Processing      The main processing done by spr_fsi is the scaling and the
		change in colour depth which are done at the same time.
		Other pre-processing options are performed before this
		in the following order.

		filter		    (modifies input image in memory)
		invert		    (modifies palette only if image <= 8bpp)
		expand		    (modifies palette only if image <= 8bpp)
		gamma		    (modifies palette only if image <= 8bpp)
		optimise palette    (only effects output image)

		Certain operations such as filtering should be done with the
		maximum bpp, and others may give better results if done after
		scaling. Two (or more) runs of spr_fsi can be performed to
		achieve the best results.
		
Deinterlacing   To remove interlace artifacts from digitised images (casued by
                the odd an even fields of a video frame differing when there
                has been movement, giving jagged edges of objects on alternate
                lines), the following processing options can be used:-
                
                Scale to half vertical height using no interpolation
                (just remove every other line)
                spr_fsi -scale 1:1,1:2 -nointerp -in <infile> -out <outfile>       		
                Scale back up to full height
                spr_fsi -scale 1:1,2:1 -in <infile> -out <outfile>
                
                Apply slight vertical sharpening (the 5 can be alterned
                to increase or decrease the effect)
                spr_fsi -filter 0,-1,0,0,5,0,0,-1,0 -in <infile> -out <outfile>


See also spr_info.

!ComndCTRL configuration file: spr_fsi
